<html>
<body>
<h1>Scala Plugin</h1>

<p>
    The Scala plugin provides support for the Scala programming language
</p>

<div id="content-before">
    <p>The plugin supports the following:</p>
    <ul style="margin-left:20px">
        <li style="list-style:square">Compilation of main and test classes via scalac or fsc</li>
        <li style="list-style:square">Scaladoc generation via scaladoc or vscaladoc</li>
        <li style="list-style:square">Compilation of mixed java and scala projects (requires scala 2.7.2+)</li>
        <li style="list-style:square">Continuous compilation that incrementally compiles modified files only.</li>
        <li style="list-style:square">Ability to run arbitrary project classes using the project paths</li>
    </ul>
    <p>Scala itself is not required - all libraries will be downloaded automatically.</p>
    <hr/>

    <h2>Scala Archetypes</h2>

    <p>If you are new to using Scala with Quokka, the best place to start is by creating a skeleton project
        using one of the scala archetypes. From an empty directory, type:</p>
    <pre>$ quokka archetype -Darchetype=quokka.archetype.scala</pre>
    <p>Follow the prompts and it will create a working project that can be used as a starting point.</p>

    <h2>Adding the scala plugin to your project</h2>

    <p>Declare the plugin in your dependency-set as follows:</p>
    <pre>&lt;dependency-set&gt;
    ...
    <b>&lt;plugin group="quokka.plugin.scala" version="?"/&gt;</b>
&lt;/dependency-set&gt;</pre>
    <p>Tip: To determine the latest version compatible with your quokka version use the <tt>quokka list-plugins</tt>
        command.</p>

    <h2>Overiding the Scala version</h2>

    <p>By default the plugin is set to the latest final release of Scala (currently 2.7.1). To use a different
        version of scala, use an override. e.g. The following overrides scala to 2.7.2-rc3:</p>
    <pre>&lt;dependency-set&gt;
    ...
    <b>&lt;override group="scala-lang" with="2.7.2-rc3" plugin-paths="*"/&gt;</b>
    &lt;plugin group="quokka.plugin.scala" version="?"/&gt;
&lt;/dependency-set&gt;</pre>

    <h2>Generating Scaladocs</h2>

    <p>By default the scaladoc related targets are not enabled. Add the <tt>docs-report</tt>
        target to enable scaladoc generation.</p>
    <pre>&lt;dependency-set&gt;
    ...
    &lt;plugin group="quokka.plugin.scala" version="?" <b>targets="docs-report"</b>/&gt;
&lt;/dependency-set&gt;</pre>
    <p>The scaladocs can then be generated with <tt>scala:docs-report</tt> or the <tt>scaladocs</tt>
        alias for the same target. The scaladocs will also be included in the developer reports
        obtained via the <tt>reports</tt> target</p>

    <h2>Using vscaladoc</h2>

    <p>If you would prefer to use vscaladoc, you need to add it as an option to the
        <tt>docs</tt> plugin path as follows:</p>
    <pre>&lt;dependency-set&gt;
    ...
    &lt;plugin group="quokka.plugin.scala" version="?" targets="docs-report" <b>paths="docs(vscaladoc)"</b>/&gt;
&lt;/dependency-set&gt;</pre>
    <p>To override the vscaladoc version, you can either use an override declaration as shown above, or
        use <tt>@</tt> shorthand notation. e.g. the following overrides vscaladoc to version 1.2</p>
    <pre>&lt;dependency-set&gt;
    ...
    &lt;plugin group="quokka.plugin.scala" version="?" targets="docs-report" <b>paths="docs(vscaladoc@1.2)"</b>/&gt;
&lt;/dependency-set&gt;</pre>

    <h2>Importing libraries from the scala-tools.org Maven repository</h2>

    <p>The quokka repository currently only contains a subset of the libraries available on scala-tools.org.
        You can import anything you need into your quokka repository using the <tt>import</tt> target of quokka's
        <a href="http://quokka.ws/quokka.plugin.maven_maven_plugin_latest.html">Maven plugin.</a>
    </p>

    <p>For the import target to find scala-tools.org, you'll need to add the following to your Maven settings.xml
        file:</p>
<pre>&lt;profile&gt;
    &lt;activation&gt;
        &lt;activeByDefault&gt;true&lt;/activeByDefault&gt;
    &lt;/activation&gt;
    &lt;id&gt;scala-tools&lt;/id&gt;
    &lt;pluginRepositories&gt;
        &lt;pluginRepository&gt;
            &lt;id&gt;scala-tools.org&lt;/id&gt;
            &lt;name&gt;Scala-tools Maven2 Repository&lt;/name&gt;
            &lt;url&gt;http://scala-tools.org/repo-releases&lt;/url&gt;
        &lt;/pluginRepository&gt;
    &lt;/pluginRepositories&gt;
    &lt;repositories&gt;
        &lt;repository&gt;
            &lt;id&gt;scala-tools.org&lt;/id&gt;
            &lt;name&gt;Scala-tools Maven2 Repository&lt;/name&gt;
            &lt;url&gt;http://scala-tools.org/repo-releases&lt;/url&gt;
        &lt;/repository&gt;
    &lt;/repositories&gt;
&lt;/profile&gt;
</pre>

<h2>Notes</h2>
<ul style="margin-left:20px">
    <li style="list-style:square">To see the scala commands being executed, turn on verbose
        logging via the command line <tt>-v</tt> switch.
    </li>
    <li style="list-style:square">By default, the only scala libraries included on the classpath
        for compilation are scala-library.jar and scala-compiler.jar. If you use any of the
        other bundled libraries such as scala-swing, or scala-dbc, you'll have to add them
        to you compile path explictly. It is unclear as to whether this is correct approach or not.
        On the one hand, you would expect anything that compiles with scalac to compile with the plugin.
        On the other hand, if your product is a server side application, you probably won't be
        running your application via scala and will need to explictly add the libraries.
    </li>
    <li style="list-style:square">vscaladoc 1.1 will not work with 2.7.2-rc3</li>
    <li style="list-style:square">The plugin automatically detects if the fsc compiler
        is running and connects to it. However, the location that fsc uses to store it's
        port number dependends on your environment. In particular, it tries to write
        it to ${scala.home}/var/scala-devel, then ${user.home}:/tmp, then ${java.io.tmpdir}.
        So unless you set the scala.home system variable (via QUOKKA_OPTS) you will probably
        end up with 2 instances of fsc running. This is harmless, but can be avoided if
        desired by setting scala.home.
    </li>
</ul>
<hr/>
</div>

<div id="after-summary">
</div>
<div id="docs-collect">
    <p>Note that the source files are configured as a file set so you can use this to
    include and exclude certain packages if desired.</p>
</div>
<div id="cc">
    The continuous compile target can be configured to continuously compile your source code. There
    are two modes of operation, manual and automatic. Manual will wait for ENTER to be hit on the console
    before re-compiling. Automatic waits for a defined interval after each compilation run and will
    then automatically re-compile again. In either mode, the commands can be entered from the console to
    modify the compilation behaviour. Each command is a single character, and multiple commands can
    be combined. The commands are:
    <table>
        <tr>
            <td>f</td>
            <td>Force compilation of all files</td>
        </tr>
        <tr>
            <td>m</td>
            <td>Turn on manual compilation (waits for ENTER before re-compiling)</td>
        </tr>
        <tr>
            <td>a</td>
            <td>Turn on automatic compilation</td>
        </tr>
        <tr>
            <td>s</td>
            <td>switch compilers (use fsc if currently scalac and vice versa)</td>
        </tr>
        <tr>
            <td>r</td>
            <td>Restart the fsc compiler server</td>
        </tr>
        <tr>
            <td>x</td>
            <td>Exit</td>
        </tr>
    </table>
    <p>For example, 'fr' would restart the compile server and force recompilation of all files. Note that commands
        are only active for the next compilation run and then will revert to defaults.</p>

    <p><b>Properties:</b></p>
    <table>
        <tr>
            <td>intervalSeconds</td>
            <td>The time in seconds to pause between compilation runs. If the interval is -1,
            compilation is set to manual.</td>
        </tr>
        <tr>
            <td>target</td>
            <td>The name of the target to execute each time</td>
        </tr>
        <tr>
            <td>useFsc</td>
            <td>If true, the fsc compiler will be used, otherwise scalac will be used.
            </td>

        </tr>
    </table>
</div>
<div id="test-compile">
    <p>See <a href="#compile">compile</a> for configuration options</p>
</div>
<div id="fsc-shutdown">
    <p>The compile server will be restarted again automatically on the next fsc compilation</p>
</div>
<div id="compile">
    <p><b>Properties:</b></p>
    <table>
        <tr>
            <td>useFsc</td>
            <td>If true, the fsc compiler will be used, otherwise scalac will be used. Defaults to false.
            </td>
        </tr>
        <tr>
            <td>compileJava</td>
            <td>If true, it will search for Java source files and compile them as well if found. This is is only supported
                on Scala versions >= 2.7.2. Note that 3 separate compilation runs are performed. The first,
                passes all scala and java source files to the scala compiler. Then the java files are compiled
                with javac. Finally, the scala source files compiled again using the scala compiler. Defaults to true.
            </td>
        </tr>
        <tr>
            <td>force</td>
            <td>If true, all source files will be recompiled. Otherwise, only those that have been modified
                will be compiled. Note that this will not pick up indirect dependencies that require
                recompilation. Defaults to false.
            </td>
        </tr>
        <tr>
            <td>srcDir</td>
            <td>The root directory of the source files
            </td>
        </tr>
        <tr>
            <td>destDir</td>
            <td>The directory where compiled classes are written to
            </td>
        </tr>
        <tr>
            <td>jvmArgs</td>
            <td>Any additional JVM arguments
            </td>
        </tr>
        <tr>
            <td>compilerArgs</td>
            <td>Any additional compiler arguments (use scalac -help to review the options available).
            </td>
        </tr>
    </table>
    <p>Javac is invoked automatically to compile any java source files. Javac can be configured by
    defining properties prefixed with <tt>javac.</tt>. See the 
        <a href="http://quokka.ws/quokka.plugin.javac_javac_plugin_latest.html">Java plugin</a> for available
    properties.</p>
</div>

<div id="docs-report">
    <p>The scaladocs can be generated using either scaladoc or vscaladoc. In the case of the latter,
    you need to add the vscaladoc library to the <tt>docs</tt> classpath (see above for examples).</p>
    <p></p>
    <p><b>Properties:</b></p>
    <table>
        <tr>
            <td>bottom</td>
            <td>Include bottom text for each page</td>
        </tr>
        <tr>
            <td>doctitle</td>
            <td>Include title for the overview page</td>
        </tr>
        <tr>
            <td>top</td>
            <td>Include top text for each page</td>
        </tr>
        <tr>
            <td>windowtitle</td>
            <td>Specify window title of generated HTML documentation</td>
        </tr>
        <tr>
            <td>footer</td>
            <td>Include footer text for each page</td>
        </tr>
        <tr>
            <td>header</td>
            <td>Include header text for each page</td>
        </tr>
        <tr>
            <td>stylesheetfile</td>
            <td>File to change style of the generated documentation</td>
        </tr>
        <tr>
            <td valign="top">options</td>
            <td>Any of the following options may be specified together:
<pre>-g:&lt;g&gt;                 Specify level of generated debugging info (none,source,line,vars,notailcalls)
-nowarn                Generate no warnings
-verbose               Output messages about what the compiler is doing
-deprecation           Output source locations where deprecated APIs are used
-unchecked             Enable detailed unchecked warnings
-encoding &lt;encoding&gt;   Specify character encoding used by source files
-target:&lt;target&gt;       Specify for which target object files should be built (jvm-1.5,jvm-1.4,msil,cldc)
-print                 Print program with all Scala-specific features removed
-optimise              Generates faster bytecode by applying optimisations to the program
-explaintypes          Explain type errors in more detail
-uniqid                Print identifiers with unique names for debugging
-access:&lt;access&gt;       Show only public, protected/public (default) or all classes and members (public,protected,private)
-charset &lt;doccharset&gt;  Charset for cross-platform viewing of generated documentation.
-linksource            Generate source in HTML
-nocomment             Suppress description and tags, generate only declarations.
</pre>
</td>
        </tr>
    </table>
</div>
</body>
</html>